home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_gtk+.idb / usr / freeware / include / gtk / gtkobject.h.z / gtkobject.h
Encoding:
C/C++ Source or Header  |  1999-07-16  |  12.8 KB  |  384 lines
  1. /* GTK - The GIMP Toolkit
  2.  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
  3.  *
  4.  * This library is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU Library General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 2 of the License, or (at your option) any later version.
  8.  *
  9.  * This library is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.     See the GNU
  12.  * Library General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU Library General Public
  15.  * License along with this library; if not, write to the
  16.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.  * Boston, MA 02111-1307, USA.
  18.  */
  19.  
  20. /*
  21.  * Modified by the GTK+ Team and others 1997-1999.  See the AUTHORS
  22.  * file for a list of people on the GTK+ Team.  See the ChangeLog
  23.  * files for a list of changes.  These files are distributed with
  24.  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  25.  */
  26.  
  27. #ifndef __GTK_OBJECT_H__
  28. #define __GTK_OBJECT_H__
  29.  
  30.  
  31. #include <gtk/gtkarg.h>
  32. #include <gtk/gtkenums.h>
  33. #include <gtk/gtktypeutils.h>
  34. #include <gtk/gtkdebug.h>
  35.  
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif /* __cplusplus */
  40.  
  41.  
  42.  
  43. /* Macro for casting a pointer to a GtkObject or GtkObjectClass pointer.
  44.  * The second portion of the ?: statments are just in place to offer
  45.  * descriptive warning message.
  46.  */
  47. #define GTK_OBJECT(object)        ( \
  48.   GTK_IS_OBJECT (object) ? \
  49.     (GtkObject*) (object) : \
  50.     (GtkObject*) gtk_type_check_object_cast ((GtkTypeObject*) (object), GTK_TYPE_OBJECT) \
  51. )
  52. #define GTK_OBJECT_CLASS(klass)        ( \
  53.   GTK_IS_OBJECT_CLASS (klass) ? \
  54.     (GtkObjectClass*) (klass) : \
  55.     (GtkObjectClass*) gtk_type_check_class_cast ((GtkTypeClass*) (klass), GTK_TYPE_OBJECT) \
  56. )
  57.  
  58. /* Macro for testing whether `object' and `klass' are of type GTK_TYPE_OBJECT.
  59.  */
  60. #define GTK_IS_OBJECT(object)        ( \
  61.   (object) != NULL && \
  62.   GTK_IS_OBJECT_CLASS (((GtkObject*) (object))->klass) \
  63. )
  64. #define GTK_IS_OBJECT_CLASS(klass)    ( \
  65.   (klass) != NULL && \
  66.   GTK_FUNDAMENTAL_TYPE (((GtkObjectClass*) (klass))->type) == GTK_TYPE_OBJECT \
  67. )
  68.  
  69. /* Macros for extracting various fields from GtkObject and GtkObjectClass.
  70.  */
  71. #define GTK_OBJECT_TYPE(obj)          (GTK_OBJECT (obj)->klass->type)
  72. #define GTK_OBJECT_SIGNALS(obj)          (GTK_OBJECT (obj)->klass->signals)
  73. #define GTK_OBJECT_NSIGNALS(obj)      (GTK_OBJECT (obj)->klass->nsignals)
  74.  
  75. /* GtkObject only uses the first 4 bits of the flags field.
  76.  * Derived objects may use the remaining bits. Though this
  77.  * is a kinda nasty break up, it does make the size of
  78.  * derived objects smaller.
  79.  */
  80. typedef enum
  81. {
  82.   GTK_DESTROYED        = 1 << 0,
  83.   GTK_FLOATING        = 1 << 1,
  84.   GTK_CONNECTED        = 1 << 2,
  85.   GTK_CONSTRUCTED    = 1 << 3
  86. } GtkObjectFlags;
  87.  
  88. /* Macros for extracting the object_flags from GtkObject.
  89.  */
  90. #define GTK_OBJECT_FLAGS(obj)          (GTK_OBJECT (obj)->flags)
  91. #define GTK_OBJECT_DESTROYED(obj)      ((GTK_OBJECT_FLAGS (obj) & GTK_DESTROYED) != 0)
  92. #define GTK_OBJECT_FLOATING(obj)      ((GTK_OBJECT_FLAGS (obj) & GTK_FLOATING) != 0)
  93. #define GTK_OBJECT_CONNECTED(obj)      ((GTK_OBJECT_FLAGS (obj) & GTK_CONNECTED) != 0)
  94. #define GTK_OBJECT_CONSTRUCTED(obj)      ((GTK_OBJECT_FLAGS (obj) & GTK_CONSTRUCTED) != 0)
  95.  
  96. /* Macros for setting and clearing bits in the object_flags field of GtkObject.
  97.  */
  98. #define GTK_OBJECT_SET_FLAGS(obj,flag)      G_STMT_START{ (GTK_OBJECT_FLAGS (obj) |= (flag)); }G_STMT_END
  99. #define GTK_OBJECT_UNSET_FLAGS(obj,flag)  G_STMT_START{ (GTK_OBJECT_FLAGS (obj) &= ~(flag)); }G_STMT_END
  100.  
  101. /* GtkArg flag bits for gtk_object_add_arg_type
  102.  */
  103. typedef enum
  104. {
  105.   GTK_ARG_READABLE     = 1 << 0,
  106.   GTK_ARG_WRITABLE     = 1 << 1,
  107.   GTK_ARG_CONSTRUCT     = 1 << 2,
  108.   GTK_ARG_CONSTRUCT_ONLY = 1 << 3,
  109.   GTK_ARG_CHILD_ARG     = 1 << 4,
  110.   GTK_ARG_MASK         = 0x1f,
  111.   
  112.   /* aliases
  113.    */
  114.   GTK_ARG_READWRITE     = GTK_ARG_READABLE | GTK_ARG_WRITABLE
  115. } GtkArgFlags;
  116.  
  117. typedef struct _GtkObjectClass    GtkObjectClass;
  118.  
  119.  
  120. /* The GtkObject structure is the base of the Gtk+ objects hierarchy,
  121.  * it ``inherits'' from the GtkTypeObject by mirroring its fields,
  122.  * which must always be kept in sync completely. The GtkObject defines
  123.  * the few basic items that all derived classes contain.
  124.  */
  125. struct _GtkObject
  126. {
  127.   /* GtkTypeObject related fields: */
  128.   GtkObjectClass *klass;
  129.   
  130.   
  131.   /* 32 bits of flags. GtkObject only uses 4 of these bits and
  132.    *  GtkWidget uses the rest. This is done because structs are
  133.    *  aligned on 4 or 8 byte boundaries. If a new bitfield were
  134.    *  used in GtkWidget much space would be wasted.
  135.    */
  136.   guint32 flags;
  137.   
  138.   /* reference count.
  139.    * refer to the file docs/refcounting.txt on this issue.
  140.    */
  141.   guint ref_count;
  142.   
  143.   /* A list of keyed data pointers, used for e.g. the list of signal
  144.    * handlers or an object's user_data.
  145.    */
  146.   GData *object_data;
  147. };
  148.  
  149. /* The GtkObjectClass is the base of the Gtk+ objects classes hierarchy,
  150.  * it ``inherits'' from the GtkTypeClass by mirroring its fields, which
  151.  * must always be kept in sync completely. The GtkObjectClass defines
  152.  * the basic necessities for the object inheritance mechanism to work.
  153.  * Namely, the `signals' and `nsignals' fields as well as the function
  154.  * pointers, required to end an object's lifetime.
  155.  */
  156. struct _GtkObjectClass
  157. {
  158.   /* GtkTypeClass fields: */
  159.   GtkType type;
  160.   
  161.   
  162.   /* The signals this object class handles. "signals" is an
  163.    *  array of signal ID's.
  164.    */
  165.   guint *signals;
  166.   
  167.   /* The number of signals listed in "signals".
  168.    */
  169.   guint nsignals;
  170.   
  171.   /* The number of arguments per class.
  172.    */
  173.   guint n_args;
  174.   GSList *construct_args;
  175.   
  176.   /* Non overridable class methods to set and get per class arguments */
  177.   void (*set_arg) (GtkObject *object,
  178.            GtkArg    *arg,
  179.            guint      arg_id);
  180.   void (*get_arg) (GtkObject *object,
  181.            GtkArg    *arg,
  182.            guint      arg_id);
  183.   
  184.   /* The functions that will end an objects life time. In one way ore
  185.    *  another all three of them are defined for all objects. If an
  186.    *  object class overrides one of the methods in order to perform class
  187.    *  specific destruction then it must still invoke its superclass'
  188.    *  implementation of the method after it is finished with its
  189.    *  own cleanup. (See the destroy function for GtkWidget for
  190.    *  an example of how to do this).
  191.    */
  192.   void (* shutdown) (GtkObject *object);
  193.   void (* destroy)  (GtkObject *object);
  194.   
  195.   void (* finalize) (GtkObject *object);
  196. };
  197.  
  198.  
  199.  
  200. /* Application-level methods */
  201.  
  202. GtkType    gtk_object_get_type        (void);
  203.  
  204. /* Append a user defined signal without default handler to a class. */
  205. guint    gtk_object_class_user_signal_new  (GtkObjectClass     *klass,
  206.                        const gchar          *name,
  207.                        GtkSignalRunType    signal_flags,
  208.                        GtkSignalMarshaller marshaller,
  209.                        GtkType           return_val,
  210.                        guint           nparams,
  211.                        ...);
  212. guint    gtk_object_class_user_signal_newv (GtkObjectClass     *klass,
  213.                        const gchar          *name,
  214.                        GtkSignalRunType    signal_flags,
  215.                        GtkSignalMarshaller marshaller,
  216.                        GtkType           return_val,
  217.                        guint           nparams,
  218.                        GtkType          *params);
  219. GtkObject*    gtk_object_new          (GtkType           type,
  220.                        const gchar          *first_arg_name,
  221.                        ...);
  222. GtkObject*    gtk_object_newv          (GtkType           object_type,
  223.                        guint           n_args,
  224.                        GtkArg          *args);
  225. void gtk_object_default_construct         (GtkObject          *object);
  226. void gtk_object_constructed          (GtkObject          *object);
  227. void gtk_object_sink      (GtkObject        *object);
  228. void gtk_object_ref      (GtkObject        *object);
  229. void gtk_object_unref      (GtkObject        *object);
  230. void gtk_object_weakref      (GtkObject        *object,
  231.                GtkDestroyNotify  notify,
  232.                gpointer         data);
  233. void gtk_object_weakunref (GtkObject        *object,
  234.                GtkDestroyNotify  notify,
  235.                gpointer         data);
  236. void gtk_object_destroy      (GtkObject *object);
  237.  
  238. /* gtk_object_getv() sets an arguments type and value, or just
  239.  * its type to GTK_TYPE_INVALID.
  240.  * if GTK_FUNDAMENTAL_TYPE (arg->type) == GTK_TYPE_STRING, it's
  241.  * the callers response to do a g_free (GTK_VALUE_STRING (arg));
  242.  */
  243. void    gtk_object_getv        (GtkObject    *object,
  244.                  guint        n_args,
  245.                  GtkArg        *args);
  246. /* gtk_object_get() sets the variable values pointed to by the adresses
  247.  * passed after the argument names according to the arguments value.
  248.  * if GTK_FUNDAMENTAL_TYPE (arg->type) == GTK_TYPE_STRING, it's
  249.  * the callers response to do a g_free (retrived_value);
  250.  */
  251. void    gtk_object_get        (GtkObject    *object,
  252.                  const gchar    *first_arg_name,
  253.                  ...);
  254.  
  255. /* gtk_object_set() takes a variable argument list of the form:
  256.  * (..., gchar *arg_name, ARG_VALUES, [repeatedly name/value pairs,] NULL)
  257.  * where ARG_VALUES type depend on the argument and can consist of
  258.  * more than one c-function argument.
  259.  */
  260. void    gtk_object_set        (GtkObject    *object,
  261.                  const gchar    *first_arg_name,
  262.                  ...);
  263. void    gtk_object_setv        (GtkObject    *object,
  264.                  guint        n_args,
  265.                  GtkArg        *args);
  266.  
  267. /* Allocate a GtkArg array of size nargs that hold the
  268.  * names and types of the args that can be used with
  269.  * gtk_object_set/gtk_object_get. if (arg_flags!=NULL),
  270.  * (*arg_flags) will be set to point to a newly allocated
  271.  * guint array that holds the flags of the args.
  272.  * It is the callers response to do a
  273.  * g_free (returned_args); g_free (*arg_flags).
  274.  */
  275. GtkArg* gtk_object_query_args    (GtkType      class_type,
  276.                  guint32    **arg_flags,
  277.                  guint         *n_args);
  278.  
  279. /* Set 'data' to the "object_data" field of the object. The
  280.  *  data is indexed by the "key". If there is already data
  281.  *  associated with "key" then the new data will replace it.
  282.  *  If 'data' is NULL then this call is equivalent to
  283.  *  'gtk_object_remove_data'.
  284.  *  The gtk_object_set_data_full variant acts just the same,
  285.  *  but takes an additional argument which is a function to
  286.  *  be called when the data is removed.
  287.  *  `gtk_object_remove_data' is equivalent to the above,
  288.  *  where 'data' is NULL
  289.  *  `gtk_object_get_data' gets the data associated with "key".
  290.  */
  291. void     gtk_object_set_data         (GtkObject         *object,
  292.                       const gchar    *key,
  293.                       gpointer          data);
  294. void     gtk_object_set_data_full    (GtkObject         *object,
  295.                       const gchar    *key,
  296.                       gpointer          data,
  297.                       GtkDestroyNotify destroy);
  298. void     gtk_object_remove_data         (GtkObject         *object,
  299.                       const gchar    *key);
  300. gpointer gtk_object_get_data         (GtkObject         *object,
  301.                       const gchar    *key);
  302. void     gtk_object_remove_no_notify (GtkObject         *object,
  303.                       const gchar    *key);
  304.  
  305. /* Set/get the "user_data" object data field of "object". It should
  306.  *  be noted that these functions are no different than calling
  307.  *  `gtk_object_set_data'/`gtk_object_get_data' with a key of "user_data".
  308.  *  They are merely provided as a convenience.
  309.  */
  310. void     gtk_object_set_user_data (GtkObject    *object,
  311.                    gpointer     data);
  312. gpointer gtk_object_get_user_data (GtkObject    *object);
  313.  
  314.  
  315. /* Object-level methods */
  316.  
  317. /* Append "signals" to those already defined in "class". */
  318. void    gtk_object_class_add_signals    (GtkObjectClass    *klass,
  319.                      guint        *signals,
  320.                      guint         nsignals);
  321. /* the `arg_name' argument needs to be a const static string */
  322. void    gtk_object_add_arg_type        (const gchar    *arg_name,
  323.                      GtkType     arg_type,
  324.                      guint         arg_flags,
  325.                      guint         arg_id);
  326.  
  327. /* Object data method variants that operate on key ids. */
  328. void gtk_object_set_data_by_id        (GtkObject     *object,
  329.                      GQuark          data_id,
  330.                      gpointer      data);
  331. void gtk_object_set_data_by_id_full    (GtkObject     *object,
  332.                      GQuark          data_id,
  333.                      gpointer      data,
  334.                      GtkDestroyNotify destroy);
  335. gpointer gtk_object_get_data_by_id    (GtkObject     *object,
  336.                      GQuark          data_id);
  337. void  gtk_object_remove_data_by_id    (GtkObject     *object,
  338.                      GQuark          data_id);
  339. void  gtk_object_remove_no_notify_by_id    (GtkObject     *object,
  340.                      GQuark          key_id);
  341. #define    gtk_object_data_try_key        g_quark_try_string
  342. #define    gtk_object_data_force_id    g_quark_from_string
  343.  
  344.  
  345. /* Non-public methods */
  346.  
  347. void    gtk_object_arg_set    (GtkObject   *object,
  348.                  GtkArg         *arg,
  349.                  GtkArgInfo  *info);
  350. void    gtk_object_arg_get    (GtkObject   *object,
  351.                  GtkArg         *arg,
  352.                  GtkArgInfo  *info);
  353. gchar*    gtk_object_args_collect (GtkType      object_type,
  354.                  GSList        **arg_list_p,
  355.                  GSList        **info_list_p,
  356.                  const gchar *first_arg_name,
  357.                  va_list      var_args);
  358. gchar*    gtk_object_arg_get_info (GtkType      object_type,
  359.                  const gchar *arg_name,
  360.                  GtkArgInfo **info_p);
  361. void    gtk_trace_referencing    (GtkObject   *object,
  362.                  const gchar *func,
  363.                  guint          dummy,
  364.                  guint          line,
  365.                  gboolean     do_ref);
  366. #if    G_ENABLE_DEBUG
  367. #  define gtk_object_ref(o)   G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,1);}G_STMT_END
  368. #  define gtk_object_unref(o) G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,0);}G_STMT_END
  369. #endif    /* G_ENABLE_DEBUG */
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378. #ifdef __cplusplus
  379. }
  380. #endif /* __cplusplus */
  381.  
  382.  
  383. #endif /* __GTK_OBJECT_H__ */
  384.